Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

SmartObject SupportedLinks and the addLink procedure

There are standard links associated with each SmartObject class. The SupportedLinks ADM property for the class names these links. Each link is defined with a set of ADM property values and functions to support getting and setting those properties and are described in this section.

SmartLinks are established when a SmartObject is created at run time, when the createobjects procedure runs addLink. All these supporting elements are already present for all of the standard shipped SmartObjects. This description is here to help developers understand how the ADM link mechanism works and how it can be extended for new SmartObject types.

SmartLinks are typically established when you define links in the Container Builder while assembling SmartWindows or other containers. When you define a template container in the Container Builder, you also define links between the objects in the template. When you define a specific window using that template, you can add additional links. For example, you can add a link that connects objects on different pages that you assemble. For each link, a record is added to the Repository to define the link. At run time, the dynamic window procedure runs addLink to create those links, as shown:

PROCEDURE addLink: Parameters: (INPUT phSource /* HANDLE – Source procedure handle */, INPUT pcLink /* CHARACTER – Link name */, INPUT phTarget /* HANDLE – Target procedure handle */). Candidate for: calling If you need to create your own additional links at runtime based on application requirements, you do this by running addLink.

The addLink procedure requires that three basic properties and supporting functions for those properties be predefined in the SmartObject support files (its include files and super procedures). In the source procedure for the link, there must be a property that holds the handle or handles of the targets for each supported link. In the target for the link, there must be a property that holds the handle or handles of the link source for each supported link. These source and target procedures use functions that set property values in linked SmartObjects or return the handles of those linked objects when needed. At startup time, addLink sets these properties to the appropriate procedure handles. The names of the properties must be <LinkType>Target in the source SmartObject, and <LinkType>Source in the target object.

In addition, addLink requires that a property must be in the target SmartObject listing the events that the target object wants to be notified of when those events are published by the source. The name of this property must be <LinkType>SourceEvents, and must be a comma-separated list of event names. If the source of the link also wants to be notified of events in the target, then there must be a <LinkType>TargetEvents property in the source SmartObject.

The addLink procedure looks at the propertyType of the <LinkType>Target and <LinkType>Source properties (which returns the data-type of the property) to determine whether the link supports a single object or multiple objects. Typically a SmartLink supports only a single source, but can support more than one target. For example, a container can contain many other SmartObjects, which are its Container-Targets, but each of those objects has a single Container-Source. Likewise, a SmartObject, such as a SmartDataObject or SmartDataViewer, can have only a single Data-Source, but an SDO can have multiple Data-Targets. Additional user-defined SmartLinks for new SmartObjects can be defined to support single or multiple sources and single or multiple targets. This is done in the definition of the properties where the handles are stored.

If the data type of the property is HANDLE (which is typically the case for the <LinkType>Source property), then this tells addLink that only a single object is permitted on that end of the link, and it runs the set<LinkType>Source function to assign the property value to the source procedure handle.

If the data type of the property is CHARACTER (which is typically the case for the <LinkType>Target property), then this tells addLink that multiple objects are permitted on that end of the link, and it runs the modifyListProperty procedure to add the target procedure handle to the list of handles of objects that are targets of that link (or the source if the source supports multiple SmartObjects). See the "Special functions that manage properties" section for a description of propertyType and modifyListProperty.

The addLink procedure then looks at the <LinkType>SourceEvents property in the target SmartObject, and subscribes the target procedure to each of those events in the source procedure handle. This causes the event procedure of the same name as the event to be run in the target each time the source publishes that event. In some cases the source of a link also receives messages from the target. In this case, there is also a <LinkType>TargetEvents property in the source SmartObject, and addLink subscribes the source to those events in the target.

The lists of the events to which source events and target events of each standard supported link are subscribed are in a series of tables in the SmartLinks chapter of the ProgressVersion 9 ADM documentation.

To look at a specific example, examine the Container link. This link is not on the list of SupportedLinks for any SmartObject because every SmartObject can be a Container-Target, and every SmartContainer™ can be a Container-Source, so this link is created automatically when a SmartContainer is run and its contents are started (the addLink call to establish the Container link is in constructObject).

Because every SmartObject can be a Container-Target, the properties that define the source handle and events are in the property include file that all SmartObjectss share, smrtprop.i. They are, of course, also defined in the Repository. The ContainerSource property is defined as data type HANDLE, to indicate that there can be only a single Container-Source for a SmartObject. The ContainerSourceEvents property lists the events to which each SmartObject is subscribed in its parent container. This list includes initializeObject, hideObject, viewObject, destroyObject, enableObject, and confirmExit. When a container is initialized, for example, it publishes initializeObject, which causes each of its child SmartObjects to be initialized as they receive that event and run their own initializeObject procedure. The supporting functions getContainerTarget, setContainerTarget, getContainerTargetEvents, and setContainerTargetEvents are defined in smart.p, the super procedure used by all SmartObjects.

Only a container can be a Container-Source, so the properties describing the target are defined in the property include file for containers, cntnprop.i, and also in the Repository. There is a ContainerTarget property (of type CHARACTER), and a ContainerTargetEvents property, because each container subscribes to a single event in each of its child objects, exitObject. The super procedure for containers, containr.p, contains the get and set functions for these properties.